package cn.song.freight.service;

import cn.song.freight.domain.dto.FreightStrategyAddDTO;
import cn.song.freight.domain.dto.FreightStrategyEditDTO;
import cn.song.freight.domain.dto.FreightStrategyQueryDTO;
import cn.song.freight.domain.dto.StrategyCopyDTO;
import cn.song.freight.domain.entity.FreightStrategyDO;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;

/**
 * 运费策略服务接口
 * <pre>
 * 该服务实现提供物流系统的运费策略管理功能，支持策略的增删改查操作，
 * 并提供基于多种条件的策略查询功能，用于维护系统中的定价策略配置。
 *
 * 核心功能：
 * - 运费策略信息的添加、删除、更新和查询
 * - 支持多条件组合查询
 * - 数据完整性校验和业务规则验证
 * - 策略状态管理和使用情况检查
 *
 * 定价模型说明：
 * 1. 基本重量定价（pricingModel=1）：使用首重+续重的定价方式
 * 2. 混合模型定价（pricingModel=2）：结合重量定价和重量区间规则的复杂定价方式
 *
 * 策略状态说明：
 * 1. 启用状态（status=1）：策略可被系统选择和使用
 * 2. 禁用状态（status=2）：策略不可被系统选择和使用
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-23
 */
public interface FreightStrategyService extends IService<FreightStrategyDO> {
    /**
     * 添加新的运费策略
     * <pre>
     * 该方法实现运费策略的添加功能，会自动设置创建时间和更新时间，
     * 并将策略信息保存到数据库中，供后续运费计算时使用。
     *
     * @param dto 运费策略添加数据传输对象，包含策略的基本信息
     * @return 添加结果，true表示添加成功，false表示添加失败
     */
    Boolean add(FreightStrategyAddDTO dto);

    /**
     * 删除指定的运费策略
     * <pre>
     * 该方法实现运费策略的删除功能，会先校验策略是否存在，
     * 并检查该策略是否已被分配使用，避免误删正在使用的策略数据，
     * 确保系统的数据一致性和业务连续性。
     *
     * @param id 要删除的运费策略ID
     * @return 删除结果，true表示删除成功，false表示删除失败
     * @throws RuntimeException 如果策略不存在或已被分配使用
     */
    Boolean delete(Long id);

    /**
     * 更新运费策略信息
     * <pre>
     * 该方法实现运费策略信息的更新功能，会先校验策略是否存在，
     * 自动设置更新时间，然后根据传入的更新数据对策略信息进行更新操作，
     * 保证策略信息的实时性和准确性。
     *
     * 特别处理：当计费模式从"首重续重+重量区间"(2)改为"首重续重"(1)时，
     * 需要清除该策略下的所有重量区间规则，因为纯"首重续重"模式不需要重量区间。
     *
     * @param dto 运费策略更新数据传输对象，包含要更新的策略ID和新信息
     * @return 更新结果，true表示更新成功，false表示更新失败
     * @throws RuntimeException 如果策略不存在
     */
    Boolean edit(FreightStrategyEditDTO dto);

    /**
     * 查询运费策略列表
     * <pre>
     * 该方法实现运费策略信息的条件查询功能，支持按名称、定价模型和状态进行查询，
     * 查询结果按创建时间倒序排列，便于查看最新的策略信息。
     *
     * @param query 运费策略查询数据传输对象，包含查询条件
     * @return 符合条件的运费策略列表
     */
    List<FreightStrategyDO> list(FreightStrategyQueryDTO query);

    /**
     * 查询运费策略详情
     * <pre>
     * 该方法根据策略ID获取指定运费策略的详细信息，
     * 用于查看策略的完整配置信息和当前状态，
     * 为策略编辑和详情展示提供数据支持。
     *
     * @param id 运费策略ID
     * @return 运费策略详细信息
     * @throws RuntimeException 如果策略不存在
     */
    FreightStrategyDO detail(Long id);

    /**
     * 复制策略数据
     * <pre>
     * 该方法复制指定策略的所有配置信息（包括地区配置和重量区间规则），
     * 但不包括策略分配信息，用于前端编辑弹框的回显。
     *
     * @param copyDTO 复制策略数据传输对象
     * @return 复制操作是否成功
     * @throws RuntimeException 如果策略不存在
     */
    Boolean copyStrategyData(StrategyCopyDTO copyDTO);
}
